Guideline: Always use set - no init-only properties.

Rationale:

• If we're going to standardize on either set or init, it's easier to standardize on set because doing so is non-breaking
• Using init means that if we do want to mutate a property after initialization, we need to clone the its containing object, which can be error-prone and isn't great for perf
• It's not clear (to me at least) that we actually rely on the immutability of any properties in protocol types

For context, the presence of init properties is a holdover from when most of the models were record types, where the language supports persistable updates using with expressions. Since we decided to move away from records going from init to set sounds reasonable.

The use of JsonNode, JsonElement, IDictionary<string, JsonElement>, and IDictionary<string, object> varies.

• These each have different pros and cons, and I'm not sure we necessarily want or need to standardize on a single one.
• We should define principles for when each is appropriate and align existing types accordingly.

What are our principles around this? I know JsonNode is mutable and JsonElement is not, but why is JsonNode use for params and results and JsonElement or IDictionary<string, JsonElement> seemingly used everywhere else particularly considering these properties are settable? And what's up with IDictionary<string, object> just for experimental capabilities?

What are our principles around this? I know JsonNode is mutable and JsonElement is not, but why is JsonNode use for params and results and JsonElement or IDictionary<string, JsonElement> seemingly used everywhere else particularly considering these properties are settable? And what's up with IDictionary<string, object> just for experimental capabilities?

Exactly what I'm wondering too 🙂 Maybe we could get an STJ expert to weigh in on this?

Edit: @eiriktsarpalis , do you have any thoughts about this?

@MackinnonBuck I've opened a new pull request, #923, to work on those changes. Once the pull request is ready, I'll request review from you.

What are our principles around this? I know JsonNode is mutable and JsonElement is not, but why is JsonNode use for params and results and JsonElement or IDictionary<string, JsonElement> seemingly used everywhere else particularly considering these properties are settable? And what's up with IDictionary<string, object> just for experimental capabilities?

Exactly what I'm wondering too 🙂 Maybe we could get an STJ expert to weigh in on this?

Edit: @eiriktsarpalis , do you have any thoughts about this?

• JsonElement is a struct with default(JsonElement) representing an invalid value (similar to ImmutableArray<T>). This makes it awkward to use in properties that are optional, typically requiring JsonElement? which adds its own complexities into the mix. This is why I originally opted for JsonNode? to encode parameters, which is a class with null naturally mapping to JSON null.
• When such concerns aren't present JsonElement is the natural choice since it's more efficient (it's basically just a annotated buffer)..
• IDictionary<string, object> is used typically in hybrid situations where you want values to both be JsonElement or potentially other .NET values that we are able to serialize into JSON. This is how AIFunction has been designed to work.

Thanks for the clarification, @eiriktsarpalis!

I'll leave the properties representing JSON objects as-is for this PR, then. Nothing jumps out at me as obviously using the wrong type.